//
//  DPUser.h
//  UITestingKit
//
//  Created by Ofri Wolfus on 29/03/07.
//  Copyright 2007 Ofri Wolfus. All rights reserved.
//

#import <Foundation/Foundation.h>



/*!
 * @abstract A protocol to which all user objects must conform.
 *
 * @discussion A user object is an object that simulates a user that
 * operates the test subject. DPQualityAssurance subclasses are
 * then responsible to make sure the application behaves as expected
 * in response to the user's actions.
 *
 * Each tests module can have at most one user class. In order to make
 * UITestingKit recognize that class, it must be the principal class of
 * the module.
 */
@protocol DPUser

/*!
 * @abstract Perform the next action of the receiver.
 *
 * @discussion This method is being periodically invoked by UITestingKit
 * in order to produce user actions. Each call should produce the next
 * step in the user's path. For example, if a user is supposed to create
 * a new document, enter some input and save that document, each of these
 * steps should be done in separate invocations.
 *
 * @result Return <code>YES</code> if the user has more actions to do,
 * and <code>NO</code> when the receiver has finished its work.
 */
- (BOOL)performNextAction;

#if defined(__OBJC2__) && __OBJC2__

@optional

/*!
 * @abstract Returns the time interval between the user's actions.
 *
 * @discussion Each user action causes a reaction in the application.
 * This reaction is being monitored by QA objects through accessibility
 * notifications. Accessibility notifications are delivered by an async
 * mechanism, and therefor UITestingKit waits some time before invoking
 * the next action of the user. The default time interval between actions
 * is 0.5 second, but can be customized by overriding this method.
 *
 * If the user implements this method, it'll be invoked after each call
 * to performNextAction. UITestingKit will then wait the returned time
 * before invoking the next action. The returned value is not cached and
 * may change according to your needs. For actions that cause a lot of
 * activity in the application you'll likely return longer interval.
 *
 * Any value that's less than or equal to 0.0 will be ignored and the
 * default 0.5 sec interval will be used instead.
 */
- (NSTimeInterval)actionsInterval;

#endif

@end

#if !defined(__OBJC2__) || !__OBJC2__

@interface NSObject (DPUser)
- (NSTimeInterval)actionsInterval;
@end

#endif
